How tag inheritance works
-------------------------

Almost everything in koji is dealing with tag and their inheritance.
What is it good for and how can it be configured?

Every tag handles its own configuration and as an administrator you
can live with just this. But true power of tag structure is hidden in
inheritance. You can compose tags, use parent products from which are
data inherited to new versions or other layered products and more.

Each tag has this set of data:

tag data
   1. architectures - here is the set of architectures which will be
      used in the moment, when given tag is used as a buildroot (in
      other words, when it is used in target definition)
   2. comps groups - similar to architectures, this data are used as
      installation groups, when tag is used as a buildroot. Generally,
      ``srpm-build`` and ``build`` groups are required in almost all
      cases. There could be also some additional groups like
      ``maven-build`` or ``livemedia-build`` for other operations,
      than just building rpms. Groups can be created and edited via
      ``*-group-*`` koji commands.
   3. maven options - If maven builds are enabled in koji environment
      (needs setup on hub's side), ``maven_support`` and
      ``include_all`` are options related to it. First says, that
      maven repositories should be generated and second one limits if
      all tagged versions of some artifact should be present in such
      repository.
package list
   Every tag carries a list of allowed packages, which can be tagged
   there and also owner of such package/tag combination. Note, that
   owner doesn't mean much in respect to who can do what. It is just a
   default recipients of notifications and can be changed in any time.
   Ownership doesn't limit anybody in un/tagging builds for that
   tag/package. This is on the other hand driven by hub policies.
   Package list simply says, what is allowed in tag (even if there is
   no build for given package).
tagged builds list
   This is the last component of tag. Obviously it is a list of builds
   for packages from previous point. It will never happen, that you'll
   see some builds for which is not package listed above.

All these three groups of data can be inherited and propagated through
inheritance chains.

Inheritance options
___________________

Whole inheritance can be edited via CLI's commands
``add-tag-inheritance`` and ``edit-tag-inheritance``. They have same
options which are described with examples here:

Simple ``add-tag-inheritance`` requires two existing tags which will
be linked together in inheritance chain.

::

   $ koji add-tag parent
   $ koji add-tag child
   $ koji add-tag-inheritance child parent
   $ koji list-tag-inheritance child
          child (168)
     ....  └─parent (167)

In the example you can see basic inheritance chain. You see ``child``
tag which is inheriting data from ``parent`` tag. Numbers behind tag
names are numeric ids, which you don't need to care about in normal
situations, but which can be useful in scripting koji. Four dots in
the beginning of line are placeholders for different inheritance
flags. These can be: M, F, I, N which denotes ``maxdepth``,
``pkg_filter``, ``intransitive`` and ``noconfig`` respectively.  All
these options can specified via CLI.

``priority``
    When you're adding new inheritance line to tag, which already has
    some parent, you would like to denote, in which part of
    inheritance chain new parent should appear. Let's continue with
    previous example.

    ::

     $ koji add-tag less-significant-parent
     $ koji add-tag-inheritance child less-significant-parent --priority 100
     $ koji list-tag-inheritance child
          child (168)
     ....  ├─parent (167)
     ....  └─less-significant-parent (169)

    What happened here is, that ``parent`` has default priority 0,
    while new one is priority 100. Lower number wins here. If you
    change your mind, you can always use ``edit-tag-inheritance`` to
    change the priority.

    .. note::
      Good rule of thumb is to not create inheritance without priority
      and use 10's or 100's steps. In such case you shouldn't need to
      update priorities, when adding something in the middle (where you
      can use e.g. priority 15 like in good old Basic times).

``maxdepth``
   For longer inheritance chains you may not want to treat whole
   chain. Let's leave our example and get more real-life situation.

   ::

    $ koji list-tag-inheritance linux3-build
         linux3-build (4380)
    ....  └─linux3-override (4379)
    ....     └─linux3-updates (4373)
    ....        └─linux2 (4368)
    ....           └─linux1 (4350)
    ....              └─linux0 (4250)

    $ koji add-tag linux4-build
    $ koji add-tag-inheritance linux4-build linux3-build --maxdepth 0
    $ koji list-tag-inheritance linux4-build
         linux4-build (4444)
    M...  └─linux3-build (4380)

   This is not, what you would see in Fedora's koji, because Fedora is
   not reusing anything from previous releases and is doing mass
   rebuilds instead, but it could have. In this case, we only want
   packages from ``linux3-build``, but not anything inherited into it.
   ``maxdepth`` does exactly this and strips the rest of inheritance
   chain.

``intransitive``
    Intransitive inheritance links are as what they say. If they are
    used somewhere deeper in inheritance chain, they will be ignored.
    It can be used for ensuring, that something will not be propagated
    by mistake. In combination with ``maxdepth`` it can mean hard stop
    even before ``maxdepth`` is reached.

``noconfig``
    While `normal` inheritance inherits everything - it means tag
    configuration, package list and tagged builds, links with this
    option are used only for propagating list of packages and builds.
    Everything else is ignored (architectures, locks, permissions,
    maven support).

``pkg-filter``
    Package filter is defined as regular expression and limits which
    packages are propagated through this link.